package v8.Class_Retained_Object_Info is
   type Retained_Object_Info is limited interface;
   type Pointer is access all Retained_Object_Info'Class;
   -- Interface for providing information about embedder's objects
   -- held by global handles. This information is reported in two ways:
   --
   --  1. When calling Add_Object_Group, an embedder may pass
   --     Retained_Object_Info instance describing the group.  To collect
   --     this information while taking a heap snapshot, V8 calls GC
   --     prologue and epilogue callbacks.
   --
   --  2. When a heap snapshot is collected, V8 additionally
   --     requests Retained_Object_Infos for persistent handles that
   --     were not previously reported via Add_Object_Group.
   --
   -- Thus, if an embedder wants to provide information about native
   -- objects for heap snapshots, he can do it in a GC prologue
   -- handler, and / or by assigning wrapper class ids in the following way:
   --
   --  1. Bind a callback to class id by calling Define_Wrapper_Class.
   --  2. Call Set_Wrapper_Class_Id on certain persistent handles.
   --
   -- V8 takes ownership of Retained_Object_Info instances passed to it and
   -- keeps them alive only during snapshot collection. Afterwards, they
   -- are freed by calling the Dispose class function.


   procedure Dispose (this : in out Retained_Object_Info) is abstract;
   -- Called by V8 when it no longer needs an instance.

   function Is_Equivalent
     (this  : in out Retained_Object_Info;
      other : Pointer
     ) return bool is abstract;
   -- Returns whether two instances are equivalent.

   function Get_Hash
     (this : in out Retained_Object_Info
     ) return intptr_t is abstract;
   -- Returns hash value for the instance. Equivalent instances
   -- must have the same hash value.

   function Get_Label
     (this : in out Retained_Object_Info
     ) return chars_ptr is abstract;
   -- Returns human-readable label. It must be a NUL-terminated UTF-8
   -- encoded string. V8 copies its contents during a call to GetLabel.


   function Get_Element_Count
     (this : in out Retained_Object_Info
     ) return intptr_t is abstract;
   -- Returns element count in case if a global handle retains
   -- a subgraph by holding one of its nodes.


   function Get_Size_In_Bytes
     (this : in out Retained_Object_Info
     ) return intptr_t is abstract;
   -- Returns embedder's object size in bytes.

   procedure Destroy (this : in out Retained_Object_Info) is abstract;
   -- protected virtual destructor

   procedure Free (this : access Retained_Object_Info) is abstract;
   -- protected virtual operator delete

end v8.Class_Retained_Object_Info;
